package com.openmanus.agent.memory;

import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * 智能体记忆系统接口
 * 定义了智能体记忆存储和检索的基本操作
 * 
 * @author OpenManus Team
 * @version 1.0.0
 */
public interface Memory {

    /**
     * 存储记忆
     * 
     * @param key 记忆键
     * @param content 记忆内容
     * @param metadata 元数据
     * @return 异步操作结果
     */
    CompletableFuture<Void> store(String key, String content, Map<String, Object> metadata);

    /**
     * 检索记忆
     * 
     * @param key 记忆键
     * @return 记忆内容
     */
    CompletableFuture<MemoryItem> retrieve(String key);

    /**
     * 搜索相关记忆
     * 
     * @param query 查询内容
     * @param limit 返回数量限制
     * @return 相关记忆列表
     */
    CompletableFuture<List<MemoryItem>> search(String query, int limit);

    /**
     * 删除记忆
     * 
     * @param key 记忆键
     * @return 异步操作结果
     */
    CompletableFuture<Boolean> delete(String key);

    /**
     * 清空所有记忆
     * 
     * @return 异步操作结果
     */
    CompletableFuture<Void> clear();

    /**
     * 获取记忆总数
     * 
     * @return 记忆总数
     */
    CompletableFuture<Long> count();

    /**
     * 检查记忆是否存在
     * 
     * @param key 记忆键
     * @return 是否存在
     */
    CompletableFuture<Boolean> exists(String key);

    /**
     * 更新记忆
     * 
     * @param key 记忆键
     * @param content 新内容
     * @param metadata 新元数据
     * @return 异步操作结果
     */
    CompletableFuture<Boolean> update(String key, String content, Map<String, Object> metadata);

    /**
     * 批量存储记忆
     * 
     * @param memories 记忆项列表
     * @return 异步操作结果
     */
    CompletableFuture<Void> batchStore(List<MemoryItem> memories);

    /**
     * 批量检索记忆
     * 
     * @param keys 记忆键列表
     * @return 记忆项列表
     */
    CompletableFuture<List<MemoryItem>> batchRetrieve(List<String> keys);
}
